BUILDER R Functions

seeds()

The seeds() function creates a seeds table, which is an input to builder().
It identifies seed catchments and assigns them an area target.

Seed catchments are the starting points for constructing benchmarks.
This function provides methods for filtering the catchments dataset and assigning area targets.

Usage

seeds(
  catchments_sf,
  filter_polygon = NULL,
  areatarget_value = NULL,
  areatarget_col = NULL,
  areatarget_polygon = NULL,
  areatarget_polygon_col = NULL
)

Arguments

  • catchments_sf: sf object of the catchments dataset with a unique identifier column: CATCHNUM.

  • filter_polygon: (Optional) sf polygon to filter catchments. Only catchments inside the polygon are kept.

  • areatarget_value: (Optional) Single area target value (in m²) to apply to all seeds.

  • areatarget_col: (Optional) Column in catchments_sf containing individual area targets.

  • areatarget_polygon: (Optional) sf polygon object holding area target values, used via spatial join.

  • areatarget_polygon_col: (Optional) Column in areatarget_polygon containing area target values.

📤 Output

A tibble of seed catchments and their assigned area targets.

Details

Filtering

If no filter is provided, all catchments in catchments_sf will be added to the seeds table.

  • To filter using a column, use dplyr::filter() before passing catchments_sf to seeds().

  • If filter_polygon is used, filtering is based on whether the centroid (using sf::st_point_on_surface()) falls inside the polygon.

Area Targets

Area targets must be in square meters (m²). Provide one of the following (priority is top to bottom):

  • Single value: areatarget_value applies to all seeds.

  • Column-based: Values from areatarget_col in catchments_sf.

  • Spatial join: Join with areatarget_polygon; values from areatarget_polygon_col. When multiple polygons overlap a catchment, the value with the most overlap is used.

Examples

Running the examples

  1. Download and unzip BEACONs R Tools

  2. Create the folder structure

# Set working directory
setwd("your/path/to/downloads")

dirpath <- getwd()

# Create the folder structure
treedir <- c("R","data","Builder_input")
for(d in treedir){
  if (!dir.exists(file.path(dirpath, d))) {
    dir.create(file.path(dirpath, d), recursive = TRUE)
  }
}
  1. Run the examples below.
library(dplyr)
library(sf)
library(utils)

source("./R/builder.R")

# Use all catchments as seeds with a single area target
catchments_sample <- readRDS("data/catchments_sample.rds")
seeds(catchments_sf = catchments_sample, areatarget_value = 1000000000)

# Use column-based area targets
catchments_sample$area_target <- 1000000000
seeds(catchments_sf = catchments_sample, areatarget_col = "area_target")

# Filter based on a column value
catchments_sample %>%
  filter(intact == 1) %>%
  seeds(catchments_sf = ., areatarget_value = 1000000000)

# Filter using a spatial polygon
ref_poly <- data.frame(
  lon = c(-138.4, -138.1, -138.1, -138.4, -138.1, -138.1, -138, -138),
  lat = c(64.3, 64.3, 64.1, 64.1, 64.3, 64.1, 64.1, 64.3),
  Areatarget = c(rep(1000000000, 4), rep(2000000000, 4))
) %>%
  st_as_sf(coords = c("lon", "lat"), crs = 4326) %>%
  group_by(Areatarget) %>%
  summarise(geometry = st_combine(geometry)) %>%
  st_cast("POLYGON") %>%
  st_transform(st_crs(catchments_sample))

seeds(
  catchments_sf = catchments_sample,
  filter_polygon = ref_poly,
  areatarget_polygon = ref_poly,
  areatarget_polygon_col = "Areatarget"
)

# save seeds as csv
seed <- seeds(catchments_sf = catchments_sample, areatarget_value = 1000000000)
write.csv(seed, file=file.path(dirpath,"Builder_input/seeds.csv"), row.names=FALSE)